GW Methods
==========

This page contains the documentation for 'GW_Methods.py'. This module provides functions needed for gravitational wave generation and simulations. The gravitational wave parameters are sampled from distributions based off of the findings of the GWTC-3 populations paper (arXiv:2111.03634). 

Function Definitions
----------------------

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.add_gw(ts, gw_waveform, t_merge)</strong>
   </div>

Injects a gravitational wave signal into a GWpy time series.

**Parameters:**

- **ts** (gwpy.timeseries.TimeSeries) - Time series to inject the GW signal into
- **gw_waveform** (pycbc.types.timeseries.TimeSeries) - Time series containing the GW waveform
- **t_merge** (float) - Merger time of the GW signal

**Returns:**

- **gwpy.timeseries.TimeSeries** - Original time series with the injected GW signal

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.get_projection(hp, hc, ifo, merger_time, ra, dec, polarization)</strong>
   </div>

Projects the GW signal onto the interferometer's location.

**Parameters:**

- **hp** (pycbc.types.timeseries.TimeSeries) - Plus polarization of the GW waveform
- **hc** (pycbc.types.timeseries.TimeSeries) - Cross polarization of the GW waveform
- **ifo** (string) - Interferometer abbreviation
- **merger_time** (float) - Merger time of the GW signal
- **ra** (float) - Right ascension of the signal
- **dec** (float) - Declination of the signal
- **polarization** (float) - Polarization angle

**Returns:**

- **pycbc.types.timeseries.TimeSeries** - h(t) strain with the GW as it would appear in the interferometer

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.get_BHBH(mass1, mass2, spin1z, spin1x, spin1y, spin2z, spin2x, spin2y, distance, eccentricity, inclination, coa_phase, f_lower, window)</strong>
   </div>

Generates a BHBH waveform given signal parameters.

**Parameters:**

- **mass1** (float) - Mass (in solar masses) of the first BH
- **mass2** (float) - Mass (in solar masses) of the second BH
- **spin1z** (float) - z spin of the first BH
- **spin1x** (float) - x spin of the first BH
- **spin1y** (float) - y spin of the first BH
- **spin2z** (float) - z spin of the second BH
- **spin2x** (float) - x spin of the second BH
- **spin2y** (float) - y spin of the second BH
- **distance** (float) - Luminosity distance in Mpc
- **eccentricity** (float) - Eccentricity of orbit
- **inclination** (float) - Inclination angle
- **coa_phase** (float) - Coalescence phase
- **f_lower** (float) - Starting frequency of the CBC signal
- **window** (bool) - Optional argument to apply a Tukey window to waveforms

**Returns:**

- **pycbc.types.timeseries.TimeSeries** - Plus polarization of the waveform
- **pycbc.types.timeseries.TimeSeries** - Cross polarization of the waveform

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.get_NSBH(mass1, mass2, spin1z, spin1x, spin1y, spin2z, spin2x, spin2y, distance, eccentricity, inclination, coa_phase, lambda2, f_lower)</strong>
   </div>

Generates a NSBH waveform given signal parameters.

**Parameters:**

- **mass1** (float) - Mass (in solar masses) of the BH
- **mass2** (float) - Mass (in solar masses) of the NS
- **spin1z** (float) - z spin of the BH
- **spin1x** (float) - x spin of the BH
- **spin1y** (float) - y spin of the BH
- **spin2z** (float) - z spin of the NS
- **spin2x** (float) - x spin of the NS
- **spin2y** (float) - y spin of the NS
- **distance** (float) - Luminosity distance in Mpc
- **eccentricity** (float) - Eccentricity of orbit
- **inclination** (float) - Inclination angle
- **coa_phase** (float) - Coalescence phase
- **lambda2** (float) - Dimensionless tidal deformability parameter of the NS
- **f_lower** (float) - Starting frequency of the CBC signal

**Returns:**

- **pycbc.types.timeseries.TimeSeries** - Plus polarization of the waveform
- **pycbc.types.timeseries.TimeSeries** - Cross polarization of the waveform

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.get_BNS(mass1, mass2, spin1z, spin1x, spin1y, spin2z, spin2x, spin2y, distance, eccentricity, inclination, coa_phase, lambda1, lambda2, f_lower)</strong>
   </div>

Generates a BNS waveform given signal parameters.

**Parameters:**

- **mass1** (float) - Mass (in solar masses) of the first NS
- **mass2** (float) - Mass (in solar masses) of the second NS
- **spin1z** (float) - z spin of the first NS
- **spin1x** (float) - x spin of the first NS
- **spin1y** (float) - y spin of the first NS
- **spin2z** (float) - z spin of the second NS
- **spin2x** (float) - x spin of the second NS
- **spin2y** (float) - y spin of the second NS
- **distance** (float) - Luminosity distance in Mpc
- **eccentricity** (float) - Eccentricity of orbit
- **inclination** (float) - Inclination angle
- **coa_phase** (float) - Coalescence phase
- **lambda1** (float) - Dimensionless tidal deformability parameter of the first NS
- **lambda2** (float) - Dimensionless tidal deformability parameter of the second NS
- **f_lower** (float) - Starting frequency of the CBC signal

**Returns:**

- **pycbc.types.timeseries.TimeSeries** - Plus polarization of the waveform
- **pycbc.types.timeseries.TimeSeries** - Cross polarization of the waveform

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.ns_mass()</strong>
   </div>

Randomly generates an individual neutron star's mass from a distribution.

**Returns:**

- **float** - NS mass in solar masses

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.bh_mass2(m1)</strong>
   </div>

Randomly generates the secondary mass of a BHBH system using a mass fraction.

**Parameters:**

- **m1** (float) - Mass (in solar masses) of the first BH

**Returns:**

- **float** - Second BH mass in solar masses

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.bhbh_mass()</strong>
   </div>

Randomly generates primary and secondary BH masses from a distribution.

**Returns:**

- **float** - Primary BH mass in solar masses
- **float** - Secondary BH mass in solar masses

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.nsbh_mass()</strong>
   </div>

Randomly generates NSBH masses from a distribution.

**Returns:**

- **float** - BH mass in solar masses
- **float** - NS mass in solar masses

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.rand_gw_params(signal, seed, precession)</strong>
   </div>

Randomly generates gravitational wave parameters needed for waveform generation based on GWTC-3 populations.

**Parameters:**

- **signal** (string) - Abbreviation of the CBC signal
- **seed** (NoneType or int) - Optional random seed
- **precession** (bool) - Optional argument to enable x & y spins

**Returns:**

- **list** - List of floats containing parameters for the GW signal

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.merger_time(ifo)</strong>
   </div>

Analytically finds the merger time of a GW signal from extrema.

**Parameters:**

- **ifo** (pycbc.types.timeseries.TimeSeries) - GW strain as it would appear in the interferometer

**Returns:**

- **float** - Merger time of GW signal

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.get_gw(probs=[1/3, 1/3, 1/3], precession=False)</strong>
   </div>

Randomly generates GW signal and parameters.

**Parameters:**

- **probs** (list) - List of floats containing probabilities of generating each type of CBC signal (BHBH, NSBH, BNS) which sum to 1
- **precession** (bool) - Optional argument to enable x & y spins

**Returns:**

- **pycbc.types.timeseries.TimeSeries** - Plus and cross polarization of waveform
- **list** - List of GW parameters
- **string** - Type of CBC signal

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.GW_Methods.gw_location(mu=10e-5, duration=100)</strong>
   </div>

Randomly generates number and location of GW signals using a Poissonian distribution.

**Parameters:**

- **mu** (float) - Poisson rate parameter; average number of GWs per second
- **duration** (float) - Duration of time series

**Returns:**

- **np.array** - Merger times of CBC signals